home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / dde / _pc / h / win < prev    next >
Encoding:
Text File  |  1992-02-10  |  12.8 KB  |  326 lines
  1. (* Title:   win.h
  2.  * Purpose: central management of RISC OS windows
  3.  *
  4.  *)
  5.  
  6. # ifndef __win_h
  7. # define __win_h
  8.  
  9. # ifndef __wimp_h
  10. # include "wimp.h"
  11. # endif
  12.  
  13. (* This module constructs a very simple idea of "window class" within RISCOS.
  14.  * RISCOS window class implementations register the existence of each window
  15.  * with this module. 
  16.  *)
  17.  
  18. (* This structure allows event-processing loops to be constructed that
  19.  * have no knowledge of what other modules are present in the program.
  20.  * For instance, the dialogue box module can contain an event-processing loop
  21.  * without reference to what other window types are present in the program.
  22.  *)
  23. type win_event_handler = ^procedure event_handler(e : wimp_eventstr_ptr;
  24.                                                   handle : pointer);
  25.  
  26. (* ************************** Claiming Events. *************************** *)
  27.  
  28.  
  29. (* ------------------------- win_register_event_handler --------------------
  30.  * Description:   Install an event handler function for a given window.
  31.  *
  32.  * Parameters:    wimp_w -- the window's handle
  33.  *                win_event_handler -- the event handler function
  34.  *                void *handle -- caller-defined handle 
  35.  * Returns:       void.
  36.  * Other Info:    This call has no effect on the window itself -- it just
  37.  *                informs the win module that the supplied function should
  38.  *                be called when events are delivered to the window.
  39.  *                To remove a handler, call with a null function pointer,
  40.  *                ie.  win_register_event_handler(w,(win_event_handler)0,0)
  41.  *                To catch key events for an icon on the icon bar register
  42.  *                a handler for win_ICONBAR,
  43.  *                   ie. win_event_handler(win_ICONBAR, handler_func, handle)
  44.  *                To catch load event for an icon on the icon bar register
  45.  *                a handler for win_ICONBARLOAD,
  46.  *                 ie. win_event_handler(win_ICONBARLOAD, load_func, handle).
  47.  *
  48.  *)
  49. const   win_ICONBAR = -3;
  50.         win_ICONBARLOAD = -99;
  51.  
  52. procedure win_register_event_handler(w : wimp_w;
  53.                 p : win_event_handler;
  54.                 handle : pointer); extern;
  55.  
  56.  
  57. (* ------------------------- win_read_event_handler ------------------------
  58.  * Description:   Read current event handler for a given window, and the
  59.  *                handle which it is passed.
  60.  *
  61.  * Parameters:    wimp_w w -- the window's handle
  62.  *                win_event_handler *p -- the handler function
  63.  *                void **handle -- the handle passed to the handler function
  64.  * Returns:       TRUE if given window is registered, FALSE otherwise
  65.  * Other Info:    This is useful for registering an alternative event handler
  66.  *                which can vet events, before passing them on to the original
  67.  *                handler.
  68.  *
  69.  *)
  70. function win_read_eventhandler(w : wimp_w;
  71.                 var p : win_event_handler;
  72.                 var handle : pointer) : boolean; extern;
  73.  
  74.  
  75. (* ------------------------- win_claim_idle_events -------------------------
  76.  * Description:   Cause "idle" events to be delivered to a given window.
  77.  *
  78.  * Parameters:    wimp_w -- the window's handle
  79.  * Returns:       void.
  80.  * Other Info:    To cancel this, call with window handle (wimp_w)-1.
  81.  *
  82.  *)
  83. procedure win_claim_idle_events(w : wimp_w); extern;
  84.  
  85.  
  86. type win_unknown_event_processor = ^function handler(e : wimp_eventstr_ptr;
  87.                                         handle : pointer) : boolean;
  88. (* You can ask to vet unknown events, before they are passed to the default
  89.  * unknown event handler. These procs return TRUE if they have dealt with the
  90.  * event.
  91.  *)
  92.  
  93.  
  94. (* --------------------- win_add_unknown_event_processor -------------------
  95.  * Description:   Add a handler for unknown events onto the front of the
  96.  *                queue of such handlers.
  97.  *
  98.  * Parameters:    win_unknown_event_processor -- handler function
  99.  *                void *handle -- passed to handler on call
  100.  * Returns:       void.
  101.  * Other Info:    The win module maintains a list of unknown event handlers.
  102.  *                An unknown event results in the "head of the list" function
  103.  *                being called; if this function doesn't deal with the event
  104.  *                it is passed on to the next in the list, and so on.
  105.  *                Handler functios should return a Boolean result to show
  106.  *                if they dealt with the event, or if it should be passed on.
  107.  *                "Known" events are as follows:
  108.  *                         ENULL, EREDRAW, ECLOSE, EOPEN, EPTRLEAVE, 
  109.  *                         EPTRENTER, EKEY, ESCROLL, EBUT
  110.  *                         and ESEND/ESENDWANTACK for the following msg types
  111.  *                             MCLOSEDOWN, MDATASAVE, MDATALOAD, MHELPREQUEST
  112.  *                All other events are considered "unknown"
  113.  *                Note: if none of the unknown event handlers deals with the
  114.  *                event, then it is passed on to the unknown event claiming
  115.  *                window (registered by win_claim_unknown_events()). If 
  116.  *                there is no such claimer, then the unknown event is 
  117.  *                ignored. 
  118.  *
  119.  *)
  120. procedure win_add_unknown_event_processor(p : win_unknown_event_processor;
  121.                 handle : pointer); extern;
  122.  
  123.  
  124. (* ------------------ win_remove_unknown_event_processor -------------------
  125.  * Description:   Removes the given unknown event handler with the given
  126.  *                handle from the stack of handlers.
  127.  *
  128.  * Parameters:    win_unknown_event_processor -- the handler to be removed
  129.  *                void *handle -- its handle
  130.  * Returns:       void.
  131.  * Other Info:    The handler to be removed can be anyway in the stack
  132.  *                (not necessarily at the top).
  133.  *
  134.  *)
  135. procedure win_remove_unknown_event_processor(p : win_unknown_event_processor;
  136.                 handle : pointer); extern;
  137.  
  138.  
  139. (* ---------------------- win_idle_event_claimer ---------------------------
  140.  * Description:   Informs caller of which window is claiming idle events.
  141.  *
  142.  * Parameters:    void
  143.  * Returns:       Handle of window claiming idle events.
  144.  * Other Info:    Returns (wimp_w)-1, if no window is claiming idle events.
  145.  *
  146.  *)
  147. function win_idle_event_claimer : wimp_w; extern;
  148.  
  149.  
  150. (* ---------------------- win_claim_unknown_events -------------------------
  151.  * Description:   Cause any unknown, or non-window-specific events to be
  152.  *                delivered to a given window.
  153.  *
  154.  * Parameters:    wimp_w -- handle of window to which unknown events should
  155.  *                          be delivered
  156.  * Returns:       void.
  157.  * Other Info:    Calling with (wimp_w)-1 cancels this
  158.  *                See win_add_unknown_event_processor() for details of which
  159.  *                events are "known".
  160.  *
  161.  *)
  162. procedure win_claim_unknown_events(w : wimp_w); extern;
  163.  
  164.  
  165. (* ------------------------- win_unknown_event_claimer ---------------------
  166.  * Description:   Informs caller of which window is claiming unknown events.
  167.  *
  168.  * Parameters:    void
  169.  * Returns:       Handle of window claiming unknown events.
  170.  * Other Info:    Return of (wimp_w)-1 means no claimer registered.
  171.  *
  172.  *)
  173. function win_unknown_event_claimer : wimp_w; extern;
  174.  
  175.  
  176.  
  177. (* ********************************* Menus. ****************************** *)
  178.  
  179.  
  180. (* ---------------------------- win_setmenuh -------------------------------
  181.  * Description:   Attaches the given menu structure to the given window
  182.  *
  183.  * Parameters:    wimp_w -- handle of window
  184.  *                void *handle -- pointer to menu structure
  185.  * Returns:       void.
  186.  * Other Info:    Mainly used by higher level RISC_OSlib routines to attach
  187.  *                menus to windows (eg. event_attachmenu()).
  188.  *
  189.  *)
  190. procedure win_setmenuh(w : wimp_w; handle : pointer); extern;
  191.  
  192.  
  193. (* --------------------------- win_getmenuh --------------------------------
  194.  * Description:   Returns a pointer to the menu structure attached to given
  195.  *                window.
  196.  *
  197.  * Parameters:    wimp_w -- handle of window
  198.  * Returns:       pointer to the attached menu (0 if no menu attached).
  199.  * Other Info:    As for win_setmenuh(), this is used mainly by higher level
  200.  *                RISC_OSlib routines (eg. event_attachmenu()).
  201.  *
  202.  *)
  203. function win_getmenuh(w : wimp_w) : pointer; extern;
  204.  
  205.  
  206. (* ************************** Event Processing. ************************** *)
  207.  
  208.  
  209. (* -------------------------- win_processevent -----------------------------
  210.  * Description:   Delivers an event to its relevant window, if such a window
  211.  *                has been registered with this module (via
  212.  *                win_register_event_handler()).
  213.  *
  214.  * Parameters:    wimp_eventstr* -- pointer to the event which has occurred
  215.  * Returns:       true if an event handler (registered with this module)
  216.  *                has dealt with the event, false otherwise.
  217.  * Other Info:    the main client for this routine is event_process(), which
  218.  *                uses it to deliver an event to its appropriate window.
  219.  *                Keyboard events are delivered to the current owner of the
  220.  *                caret.
  221.  *
  222.  *)
  223. function win_processevent(e : wimp_eventstr_ptr) : boolean; extern;
  224.  
  225.  
  226. (* ****************************** Termination. *************************** *)
  227.  
  228.  
  229. (* --------------------------- win_activeinc -------------------------------
  230.  * Description:   Increment by one the win module's idea of the number of
  231.  *                active windows owned by a program.
  232.  *
  233.  * Parameters:    void
  234.  * Returns:       void.
  235.  * Other Info:    Note: event_process() calls exit() on behalf of the program
  236.  *                when the number of active windows reaches zero
  237.  *                Programs which wish to remain running even when they have
  238.  *                no active windows, should ensure that win_activeinc() is
  239.  *                called once before creating any windows, so that the no.
  240.  *                of active windows is always >= 1. This is done for you
  241.  *                if you use baricon() to install your program's icon on the
  242.  *                iconbar.
  243.  *
  244.  *)
  245. procedure win_activeinc; extern;
  246.  
  247.  
  248. (* ---------------------------- win_activedec ------------------------------
  249.  * Description:   Decrements by one the win module's idea of the number of
  250.  *                active windows owned by a program.
  251.  *
  252.  * Parameters:    void
  253.  * Returns:       void.
  254.  * Other Info:    See note in win_activeinc() regarding program termination.
  255.  *
  256.  *)
  257. procedure win_activedec; extern;
  258.  
  259.  
  260. (* ---------------------------- win_activeno -------------------------------
  261.  * Description:   Informs the caller of the number of active windows owned
  262.  *                by your program.
  263.  *
  264.  * Parameters:    void
  265.  * Returns:       no. of active windows owned by program.
  266.  * Other Info:    This is given by (no. of calls to win_activeinc()) minus
  267.  *                (no. of calls to win_activedec())
  268.  *                Note that modules in RISCOSlib itself may have made calls
  269.  *                to win_activeinc() and win_activedec().
  270.  *
  271.  *)
  272. function win_activeno : integer; extern;
  273.  
  274.  
  275. (* -------------------------- win_give_away_caret --------------------------
  276.  * Description:   gives the caret away to the open window at the top of the
  277.  *                WIMP's window stack (if that window is owned by your
  278.  *                program).
  279.  * 
  280.  * Parameters:    void
  281.  * Returns:       void.
  282.  * Other Info:    If the top window is interested it will take the caret
  283.  *                If not then nothing happens.
  284.  *                Note: only works if polling is done using the wimpt module,
  285.  *                which is the case if your main inner loop goes something
  286.  *                like:   while (TRUE)
  287.  *                            event_process();
  288.  *
  289.  *)
  290. procedure win_give_away_caret; extern;
  291.  
  292. (* ------------------------------ win_settitle -----------------------------
  293.  * Description:   changes the title displayed in a given window
  294.  *
  295.  * Parameters:    wimp_w w      -- given window's handle
  296.  *                char *newtitle -- null-terminated string giving new
  297.  *                                  title for window
  298.  *
  299.  * Returns:       void.
  300.  * Other Info:    The title icon of the given window must be indirected text
  301.  *                This will change the title used by all windows created
  302.  *                from the given window's template if you have used the
  303.  *                template module (since the Window manager uses your address
  304.  *                space to hold indirected text icons). To avoid this the 
  305.  *                window can be created from a copy of the template, ie.
  306.  *                    template *t = template_copy(template_find("name"));
  307.  *                    wimp_create_wind(t->window, &w);
  308.  *
  309.  *)
  310. procedure win_settitle(w : wimp_w; newtitle : string); extern;
  311.  
  312. (* ------------------------------ win_init ---------------------------------
  313.  * Description:   initialise the centralised window event system
  314.  *
  315.  * Parameters:    void
  316.  * Returns:       TRUE if initialisation went OK.
  317.  * Other Info:    If you use wimpt_init(), to start your application, then
  318.  *                this call is made for you.
  319.  *
  320.  *)
  321. function win_init : boolean; extern;
  322.  
  323. #endif
  324.  
  325. (* end win.h *)
  326.